Skip to main content

Aspect Template Families

The Forge CLI ships a curated catalog of Aspect templates derived from real production patterns that we see across FIs. Each template is paired with one or more presets (vendor-neutral shortcuts) that fill in mock partner URLs so you can preview, edit, and validate end-to-end integration without leaving your laptop.

This page is a quick map of those families. Use it to find the closest starting point for an integration, then run forge aspect templates --id <id> for the full prompt list and forge aspect preview --template <id> --preset <id> to see it in action.

For the authoritative preset list, run forge aspect templates --format preset-ids.

How Templates Are Organized​

AxisValuesWhat it controls
platformweb, mobile, bothWhich surfaces the template can target. Mobile-only families emit full WebView HTML.
categorycontext-less, context-awareWhether the snippet reads dbk.sessionInfo() / OIDC / a JSBridge token.
contextMethodglobal-variable, oidc, jsbridge-token (context-aware only)The session-bridging boilerplate the template emits.

You can filter the catalog interactively:

Bash
forge aspect templates --platform web --context-aware
forge aspect templates --platform mobile
forge aspect templates --preset engagement-script-loader

Family Catalog​

Vendor Script Loader​

  • Template id: vendor-script-loader
  • Platform: both  ·  Category: context-less
  • Pattern: A single dbk.loadScript(url) call that points at a vendor SDK which self-mounts (chat bubble, engagement banner, etc.). No personalization needed.
  • What the user sees / CTA: Whatever the vendor SDK draws — typically a floating chat or engagement bubble.
  • Action behavior: All interaction is owned by the vendor SDK after load.
  • Presets:
    • engagement-script-loader — Mock engagement/chat SDK served from the local mock partner server.
  • Production examples it replaces: The "drop-in chat / engagement loader" Aspects deployed for ~25% of FIs.

Vendor Script with Config​

  • Template id: vendor-script-with-config
  • Platform: both  ·  Category: context-less
  • Pattern: Loads a vendor JS + CSS pair, but first writes tenant-flavored configuration onto window.* so the SDK can pick it up on init.
  • What the user sees / CTA: A vendor widget themed to the FI (retail vs business flavors are common).
  • Action behavior: The vendor SDK reads window.AspectConfigContent (or similar) and customizes itself before mounting.
  • Presets:
    • script-config-retail — Retail SSO handoff config, served from /script-config/handoff/retail.
    • script-config-business — Business / treasury handoff config, served from /script-config/handoff/business.

Tag Manager​

  • Template id: tag-manager
  • Platform: web  ·  Category: context-less
  • Pattern: Standard Google Tag Manager bootstrap (dataLayer + script injection) for a single container id. Web-only — mobile native analytics use platform SDKs, not GTM.
  • What the user sees / CTA: Nothing visible. Analytics events are captured server-side.
  • Action behavior: Pageviews and configured custom events flow into GTM → downstream analytics.
  • Presets:
    • tag-manager-mock — Mock GTM container GTM-MOCK000 so the snippet works against the local vendor server.

Hidden Iframe SSO Handoff​

  • Template id: hidden-iframe-sso
  • Platform: both  ·  Category: context-aware  ·  Method: global-variable
  • Pattern: Mounts a hidden iframe pointed at a vendor handoff endpoint, which postMessages back an SSO token. The Aspect listens, validates the origin, and forwards the token to whatever vendor surface needs it.
  • What the user sees / CTA: Nothing — the iframe is display:none. The visible UI is whatever the vendor surface renders after the token lands (for example, chat, secure messaging, etc.).
  • Action behavior: On message the Aspect either dispatchEvents a custom ready event or hands the token to a follow-up SDK init.
  • Presets:
    • iframe-sso — Local /sso/handoff mock that posts back a synthetic access_token.
  • Optional flag: webviewGate: true skips mount when dbk.isWebview() is true.

Vendor SDK with Personalization​

  • Template id: vendor-sdk-personalized
  • Platform: both  ·  Category: context-aware  ·  Method: global-variable
  • Pattern: Loads a vendor SDK and pre-seeds it with dbk.sessionInfo() before the SDK boots — so chat starts already knowing the user's name and id.
  • What the user sees / CTA: A vendor chat / co-browse / engagement widget where the user is already identified.
  • Action behavior: Click → vendor SDK opens with PreChatFields (or equivalent) prepopulated.
  • Presets:
    • embedded-service-chat — Mock embedded service chat SDK.
    • contact-center-chat — Mock contact-center chat plugin.
    • cobrowse-chat — Mock co-browse / chat widget.

Floating Action Button​

  • Template id: floating-action-button
  • Platform: both  ·  Category: context-less
  • Pattern: A fixed-position button (icon is optional) that opens a URL in a new tab. Captures the "help / FAQ deep link" pattern that several FIs roll on their own.
  • What the user sees / CTA: A circular button anchored to the bottom-right with the configured label / icon.
  • Action behavior: Click → window.open(url, '_blank', 'noopener,noreferrer').
  • Presets:
    • fab-help — Help icon FAB pointed at the local /help mock route.

Mobile Vendor Chat (JSBridge)​

  • Template id: mobile-vendor-chat-jsbridge
  • Platform: mobile  ·  Category: context-aware  ·  Method: jsbridge-token
  • Pattern: Mobile-only WebView template. Requests a session token via the native JSBridge (iOS webkit.messageHandlers.tokenApiDetails, Android JSBridge.tokenApiDetails) and uses it to init a vendor chat SDK. Falls back to a POST /token endpoint when no JSBridge is present so the template is also previewable in dev.
  • What the user sees / CTA: A vendor mobile chat experience already authenticated as the user.
  • Action behavior: The Aspect dispatches cdx-mobile-vendor-ready once the token + SDK are loaded; the vendor SDK listens and bootstraps itself.
  • Presets:
    • mobile-chat-jsbridge — Mock mobile chat SDK (JSBridge token flow).
    • mobile-embedded-chat — Mock mobile embedded service chat SDK.

Previewing Against the Mock Partner Server​

All presets default to http://localhost:4011, which is served by the public cdx-mock-partners repository. It serves:

  • GET /vendors/<vendor>/<file> — mock vendor SDK assets (JS/CSS).
  • GET /sso/handoff — fake SSO landing page used by hidden-iframe-sso.
  • POST /token — fake JSBridge token endpoint used by mobile-vendor-chat-jsbridge.
  • GET /script-config/handoff/:variant — JSON config for vendor-script-with-config.
  • GET /help — destination for the floating-action-button preset.

forge aspect preview automatically detects whether the mock partner server is up and uses it when present, so the typical workflow is:

Bash
# In one terminal — start cdx-mock-partners
cd cdx-mock-partners && pnpm install && pnpm start

# In another — preview a template
forge aspect preview --template vendor-sdk-personalized --preset embedded-service-chat

Each mock SDK draws a MOCK · pill with the partner name (usually bottom-right). Click the pill (or press Enter while it is focused) to open a panel that summarizes what the real integration does, offers one-click simulated partner actions (appended to window.__mockPartnerCalls), and shows the rolling call log. The hidden-iframe-sso template adds a separate MOCK · SSO pill (bottom-left) after the token arrives; click it to inspect the mock payload. The floating-action-button preset shows a brief Opening help… status chip before the new tab, and the /help mock page includes a Reveal typical post-navigation content control so you can see a second-step interaction without a real CMS.

One-page gallery​

Once cdx-mock-partners is up and cdx-forge-cli has been built (sibling checkout; see that repo’s README for FORGE_CLI_DIST), visit http://localhost:4011/gallery. The gallery lists every (template, preset) combo we ship and runs the real generated code in a sandboxed iframe on the right. It's the fastest way to eyeball every family without spinning up the OLB Docker playground.

OLB Docker Shell

For the full OLB Docker shell (widgets + Aspect Manager), see Web Playground.

Authoring Your Own​

When you want a behavior that isn't covered by an existing family:

  1. Start from the closest preset — forge aspect preview --template <id> --preset <id> and edit the prompts/options.
  2. Generate a file you can edit: forge aspect preview --template <id> --preset <id> --preview-code > my-aspect.js.
  3. If the pattern recurs across FIs, propose a new template upstream. The CLI's README.md has the contributor checklist (mock SDK + e2e test + PII scan).

For additional details on how Aspects execute, see the Web Technical Reference and Mobile Technical Reference sections.